home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d12 / njsort11.arc / NJSORT.DOC < prev    next >
Text File  |  1989-01-02  |  17KB  |  389 lines

  1.  
  2.  
  3. Nifty James' Famous Sort Tool
  4. Version 1.00 of 08 May 1988
  5. Version 1.05 of 19 May 1988
  6. Version 1.10 of 03 July 1988
  7. Version 1.11 of 30 October 1988
  8.  
  9. (C) Copyright 1988 by Mike "Nifty James" Blaszczak
  10.  
  11.  
  12.  
  13. REDISTRIBUTION OF THIS PROGRAM WITHOUT THE PRIOR WRITTEN CONSENT OF
  14. THE AUTHOR IS STRICTLY PROHIBITED.  THIS PROGRAM MAY NOT BE RESOLD OR
  15. OFFERED AS INSENTIVE FOR PURCHASE WITHOUT THE AUTHOR'S KNOWLEDGE.
  16. THE AUTHOR IS NOT RESPONSIBLE FOR DAMAGES, DIRECT OR CONSEQUENTIAL,
  17. CAUSED BY THE APPLICATION OR MISAPPLICATION OF THIS PROGRAM.
  18.  
  19.  
  20.  
  21. It is very often necessary to sort information.  It makes the
  22. retrevial of information more rapid, and gives the data a more
  23. humanized look.  It also facilitates maintenance of lists.
  24.  
  25. Thus, having a powerful sorting tool is essential to good
  26. productivity.  This program is capable of very large lists, and is
  27. limited only by the availability of storage space.  It runs very
  28. quickly, using optimized C code and hand-written assembly language
  29. for the more crucial routines.
  30.  
  31. Using NJSORT is quite easy; it is run from the command line using a
  32. traditional syntax:
  33.  
  34.     NJSORT <infilename> [<outfilename>] [<options>]
  35.  
  36. <infilename> is the name of the input file -- the file to be sorted.
  37. It must be present.  If it is not, NJSORT will show its usage and
  38. syntax and terminate.
  39.  
  40. <outfilename> specifies the name of the output file.  If this name is
  41. not present, NJSORT will write the sorted output to the same disk and
  42. directory as the input fille, but will change the extention to
  43. ".BAK".  For this reason, you must specify an alternate output file
  44. name if you would like to use NJSORT to sort a file with the
  45. extention of ".BAK".
  46.  
  47. <options> is a list of options.  These are the valid options:
  48.  
  49.     /B    Strip blank lines from the input.  If a line is found to
  50.     have nothing on it, or only tabs and spaces on it, NJSORT
  51.     will remove it from the output file if this option is
  52.     specified.
  53.  
  54.     /C    Case Insensitive sort.  This will tell NJSORT not to pay
  55.     attention to the case of the text it is sorting.  NJSORT
  56.     will consider "lowercase" equal to "LOWERCASE", for example.
  57.  
  58.     /D    Remove duplicate lines.  This will cause NJSORT to remove
  59.     identical lines from the output.  If /C is specified, the
  60.     comparison for duplicate lines will not be case sensitive.
  61.     If /I is specified, the check for duplicate lines will not
  62.     pay attention to leading whitespace.
  63.  
  64.     /I  Ignore leading whitespace.  This will cause NJSORT to ignore
  65.     the tabs or spaces at the beginning of a line.
  66.  
  67.     /R  Sort in reverse order.  Normally, NJSORT sorts starting with
  68.     the lowest ASCII code and going up.  Thus, 'A' comes before
  69.     'Z'.  If this option is specified, NJSORT will sort starting
  70.     with the highest ASCII code and going down: 'Z' will come
  71.     before 'A'.
  72.  
  73.     /V  Display sort statistics.  This verbose mode will display
  74.     information about the sorting process after it has completed.
  75.  
  76. Normally, NJSORT sorts ASCII files by looking at each line as a
  77. separate item.  Often times, there may be more than one sort field on
  78. each line.  It may also be desirable to sort the text based on the
  79. content of a certain colum or field of data.
  80.  
  81. To make use of this feature, these options may be used:
  82.  
  83.    /F#    Specify the first key field number
  84.    /S#    Specify the second key field number
  85.    /T#    Specify the third key field number
  86.    /Q#    Specify the fourth key field number
  87.    /P#    Specify the fifth key field number
  88.    /M,    Specify field delimiter
  89.    /N     Sort by columns and not fields
  90.  
  91. These options define the fields to be used, and their respective
  92. "weight" in the sort.  When no fields are specified, NJSORT uses the
  93. entire line starting at the beginning as the sort key.
  94.  
  95. When a key field is specified, NJSORT checks them in order.  If the
  96. first key field of two items are equal, then the second key field is
  97. checked.  If the second key field is equal, then the third is
  98. compared, and so on.  If all the specified key fields are equal, or
  99. there are no more key fields on the line, the items are assumed to be
  100. equal and their final order is arbitrary.
  101.  
  102. Since I maintain a database of the records in my collection, I have
  103. an ASCII file with this format:
  104.  
  105.    <artist>,<album>,<song>,<length>,<sidecut>,<copyright>
  106.  
  107. A typical entry might look like this:
  108.  
  109.    Pink Floyd,Dark Side of The Moon; The,Money,6:23,0201,73
  110.  
  111. I can sort this database using the command
  112.  
  113.    NJSORT MUSIC.DAT /F1 /S2 /T3 /Q5 /F6 /M, /C
  114.  
  115. This uses the /C option to make the sort case insensitive; thus,
  116. "PINK FLOYD" will be equal to "Pink Floyd".  The program is told
  117. which keys to order the sort with, and it is told that the comma
  118. spearates the felds of data.
  119.  
  120. Thus, when NJSORT sees the line in the file, it looks at it like
  121. this:
  122.  
  123.    Pink Floyd,Dark Side of The Moon; The,Money,6:23,0201,73
  124.     Field 1  |   Field 2                |  3  |    |  4 |  5
  125.  
  126. When it sorts the file, the list will be ordered  by the name of the
  127. artist.  "Pink Floyd" will come before "ZZ Top".  If NJSORT finds
  128. that the first field of two items are equal, it will check the second
  129. field.  "Dark Side of The Moon; The" comes before "Wall; The", even
  130. thoug they are both Pink Floyd albums.
  131.  
  132. If the program finds that the album names in the second field are
  133. equal, it will check the third field,  which is the song title.  In
  134. the unlikely event  they are also equal, the program will also go on
  135. to check the side and cut of the song on the album, and finally the
  136. copyright date of the song.
  137.  
  138. This allows you to sort with multiple keys on fields with variable
  139. length.  If the file, however, is listed in columns, for example:
  140.  
  141.     Pink Floyd     Dark Side of The Moon; The   Money
  142.     Pink Floyd     Dark Side of The Moon; The   Eclipse
  143.     .
  144.     .
  145.     .
  146.  
  147. NJSORT should be given the option /N, which tells the program to use
  148. the numbers provided ot the key field options as column numbers.  So,
  149. to sort the above file, one would use
  150.  
  151.     NJSORT MUSIC.DAT /F1 /S16 /T45 /C /N
  152.  
  153. NJSORT will reguard the field starting in the first colum as the
  154. first sort key.  The second key will start in column 16, and the
  155. third key starts in column 45.  To have NJSORT regard these numbers
  156. as column numbers, the /N option must be specified.
  157.  
  158. With Version 1.10, NJSORT also has the ability to sort binary files
  159. that contain fixed-length records.  You can specify the offset of
  160. the sort keys in each record using the /F, /S, /T, /Q, and /P
  161. options, as normal.  You must also specify the /W option.  The /W
  162. option must be immediately followed by the number of bytes in each
  163. record of the input file.
  164.  
  165. NJSORT will sort the records, and will write out a binary file of the
  166. same format -- just the records will be rearranged.  If NJSORT can't
  167. read a full record, it will stop and print an error message.
  168.  
  169. Using NJSORT is as simple as that, even for all its power and
  170. versatility.
  171.  
  172. NJSORT will read the datafile when it is invoked, and will then
  173. attempt to sort all the information in memory.  If the program cannot
  174. load the entire input file in one attempt, it will sort the contents
  175. of memory and write it to a temporary disk file.  It will then clear
  176. the memory, and read again.  Once all the input has been read, the
  177. program will then merge the temporary files into an output file.
  178.  
  179. NJSORT will look for the environment variables NJTEMP, TEMP, and TMP
  180. to see if a path or drive for the temporary files was specified. The
  181. first variable found will be used for the temporary file area.
  182. Specifying no variable will result in the temporary files being
  183. stored on the current drive in the current directory. Using a large
  184. RAM disk, such as NJRAMD, for the temporary files will greatly
  185. increase the speed with which the merge takes place.  The area
  186. specified for the temporary area, however, must be large enough to
  187. hold the entire file.
  188.  
  189. This "sort and merge" method allows NJSORT to sort files that are
  190. much larger than memory.  However, in the worst case, NJSORT will
  191. need twice the lenght of the file available as free space to sort 
  192. the file.  If, for example, you have a 100000 character file to
  193. sort, you must have at least 200000 bytes of free space on the
  194. diskette you wish to sort on.
  195.  
  196. If you specify an alternate temporary directory, NJSORT only needs
  197. enough space to store the output file.  The disk will contain the
  198. 100000 byte file and the 100000 byte output file, and the TEMP
  199. directory will contain the 100000 bytes of temporary files.
  200.  
  201. On my 640k system, with 580k after DOS and all TSRs are loaded,
  202. NJSORT can typically sort files between 450 and 500 kilobytes in
  203. length without having to use temporary disk files.
  204.  
  205. The complete sourcecode to the program is included in NJSORT.C and
  206. COMPARES.ASM.  The makefile used to build the program is called
  207. NJSORT.  I used BREIF to edit all the files here.  Since I am a fool
  208. for good formatting, I set BRIEF's tab stops at every three
  209. characters for .C files and at the 
  210.  
  211. This program is a work of Shareware.  I am requesting a $10
  212. registration if you like the program.  If you do not like, or do not
  213. use, the program, please pass it on to a friend or another BBS.
  214.  
  215. Currently, I have not found any bugs in NJSORT.  I have run billions
  216. of bytes of data through it in constructing and testing the program. 
  217. I have not found any problems with even the largest files using many
  218. keys and fields.
  219.  
  220. One note, however.  Even if the input file contains an end of file
  221. marker, NJSORT will NOT write the marker to the output file.  For
  222. this reason, the output file may be one byte shorter than the input
  223. file.
  224.  
  225.  
  226. Thank you very much!
  227.  
  228.  
  229. Mike "Nifty James" Blaszczak
  230. 35 Ginger Lane #229
  231. East Hartford, Connecticut
  232.     06118
  233.  
  234.  
  235. Version 1.10 Changes ---
  236.  
  237. Version 1.10 implemented the /W# option to allow sorting of
  238. fixed-length fields.  This option may be specified to cause NJSORT to
  239. treat the input file as a file of records that are the of the
  240. specified length.  No terminating character will be looked for in the
  241. records; they will simply be read as blocks of bytes.
  242.  
  243. This option does not work with the /I option to ignore whitespace. 
  244. It also will not work with the /C option to fix case, or the /D
  245. option to blast duplicate lines.  Of course, the /N and /M options
  246. are not allowed, either, as they support different reading methods.
  247.  
  248. The sort key options may be used.  They will specify the byte offsets
  249. into the records at which keys should be considered.  /F0 is the
  250. first byte of the record, for example.
  251.  
  252. If the file to be sorted contains incomplete records, NJSORT will not
  253. complete the sort.  Besides swapping the records, no other action is
  254. taken upon the binary data.
  255.  
  256. The new version contains a small change that allows more items to be
  257. sorted in memory.  Previously, NJSORT would create a temporary file
  258. if more than 8000 items need to be sorted.  Now, NJSORT will wait
  259. until there are 13000 items in memory before creating a
  260. temporary file.  This improves efficiency if the items in memory are
  261. all rather short.
  262.  
  263. Version 1.10 corrected some bugs that came about when sorting files
  264. larger than memory.  There were a handful of other minor bugs
  265. corrected throughout the program.
  266.  
  267. In Version 1.10, the COMPARES.ASM module was changed for the
  268. Microsoft Macro Assembler Version 5.10.  This will allow
  269. compatibility for a possible later release of NJSORT which will use
  270. the newer Microsoft Languages to provide compatibility with NJSORT
  271. and versions of OS/2.
  272.  
  273.  
  274. Version 1.11 Changes ---
  275.  
  276. A user in Hawaii provided most of the feedback that brought about
  277. this new version.  A problem in NJSORT's merge caused records to be
  278. dropped in some larger-than-memory sorts.  This problem has been
  279. corrected, and NJSORT should no longer lose information while sorting
  280. larger files.
  281.  
  282. An additional option has also been added to NJSORT; /O#.  This option
  283. will allow the user to have NJSORT ignore the first records of the
  284. file to be sorted.  As an example, /O5  would cause NJSORT to read
  285. the first five records or lines from the input file and write them to
  286. the ouput file without changing their order.
  287.  
  288. NJSORT underwent a few other changes to improve its speed.  The
  289. program should prove to be slightly more efficient than the previous
  290. version.
  291.  
  292. Previously, NJSORT would incorrectly report the number of records or
  293. lines sorted.  This has been fixed in the new version.
  294.  
  295.  
  296. NJSORT Error Messages
  297.  
  298. These are the error messages that NJSORT can generate, and the cause
  299. for each:
  300.  
  301. NJSORT: Can't Sort a file with extension .BAK
  302.     A file with the extension of .BAK was supplied to NJSORT as
  303.     the filename to sort.  Since NJSORT names the sorted output
  304.     with the filename extension of .BAK, the program will not
  305.     sort input files with the extension .BAK
  306.  
  307. NJSORT: Not enough memory
  308.     There was not enough memory to set up the basic housekeeping
  309.     data areas that NJSORT needs.  Generally, NSORT will require
  310.     no more ten kilobytes of memory for its own internal data and
  311.     buffer space.  You should never see this error -- if you do,
  312.     please make a note of the circumstances (computer, main
  313.     memory, TSRs loaded, file size to be sorted, command line
  314.     options, and DOS version) and send me the information.
  315.  
  316. NJSORT: Can't write record number # in file "Filename"
  317. NJSORT: Can't write line number # in file "Filename"
  318.     These errors can occur when NJSORT can not write to a file. 
  319.     If NJSORT runs out of space while writing a temporary file,
  320.     or if the program runs out of space while writing the ouput
  321.     file, this error will result.  Try to create more free space
  322.     on the device, or use another device that has more room.
  323.  
  324. NJSORT: Record # was incompletely read, only # of # bytes
  325.     In a Binary record sort, if NJSORT tries to read a record of
  326.     the specified length and actually reads less information than
  327.     that, this error will result.  The most common cause of this
  328.     error is specifying a record length that is not divisible by
  329.     the size of the file to be sorted.  For example, if the file
  330.     is 1050 bytes long and a record length of 100 was specified,
  331.     NJSORT would only find ten 100 byte records; the remaining 50
  332.     bytes would not constitute a full, sortable record.
  333.  
  334. NJSORT: Input line # exceeds 2047 characters
  335.     NJSORT cannot handle records longer than 2047 characters when
  336.     doing an ASCII sort.  The input file is simply too wide to
  337.     sort.  This error also comes about when NJSORT gets a binary
  338.     file and wasn't given the /W parameter.
  339.  
  340. NJSORT: there weren't enough input records to skip
  341.     You told NJSORT to skip more records than were actually found
  342.     in the input file.  Lessen the number of records to skip.
  343.  
  344. NJSORT: can't have both <something> and <something else>
  345.     When parsing the options specified, NJSORT found two
  346.     conflicting options.  Some options are incompatible; for
  347.     example, you can not specify both /W and /M.
  348.  
  349. NJSORT: key offset greater than recwidth
  350.     In a Binary Sort, NJSORT realized a record with was specified
  351.     and one of the keys was given as having an offset greater than
  352.     that record width.  Check the parameters that you gave.
  353.  
  354. NJSORT: must have at least one field with /M or /N
  355.     The /M and /N options imply the use of sorting fields, and no
  356.     field size or offset was specified.
  357.  
  358. NJSORT: <key> was too big
  359.     One of the specified key widths was larger than 2047, the
  360.     maximum record size for NJSORT.
  361.  
  362. NJSORT: Can't open <filename> for input
  363.     The specified file was not found or was not available to
  364.     NJSORT for read access.
  365.  
  366. NJSORT: Can't open <filename> for output
  367.     The requested or default output file was not valid or could
  368.     not be created by NJSORT.
  369.  
  370. NJSORT: Too many temporary files!  Could not sort.
  371.     NJSORT needed to use more than eighteen temporary files, and
  372.     could not do so.  This error should only occur when sorting
  373.     files in the range of four to ten megabytes -- if it happens
  374.     in less demanding circumstances, inform the author.
  375.  
  376. NJSORT: Couldn't setup temporary buffer
  377.     A problem occurred with NJSORT while trying to manipulate a
  378.     temporary file.  This error should rarely occur.  If it
  379.     happens twice, make a note of the environment and notify the
  380.     author.
  381.  
  382. NJSORT: Couldn't open file <filename> for temporary use
  383.     There was a problem in accessing a temporary file.  This
  384.     should not occurr, unless the temporary file area ran out of
  385.     space just as NJSORT was opening the file.  Also, in a
  386.     multiuser environment, if another program attempts to
  387.     manipulate NJSORT's temporary file, this error may result.
  388.  
  389.